Info file texinfo, produced by texinfo-format-buffer
from file texinfo.texinfo

File: texinfo  Node: top, Up: (DIR), Next: commands

Texinfo Files
*************

Documentation for GNU utilities and libraries should be written in a
format called "texinfo".  This format can be translated mechanically
into either printed manuals or on-line readable Info files.

* Menu:

* commands::   What goes into a texinfo file.
* info::   Making a texinfo file into an Info file.
The following will be written later
  tex::    Making a texinfo file into a printed manual.

File: texinfo  Node: commands, Prev: top, Up: top, Next: info

Texinfo File Commands
=====================

Texinfo files contain a strictly limited set of constructs
for a TeX macro package quite different from plain TeX.
The strict limits make it possible for texinfo files to be
understood also by the `texinfo' program, which converts
them into Info files.

All ASCII printing characters except `@', `{' and `}' can appear
in body text in a texinfo file and stand for themselves.  `@' is the
escape character which introduces commands.  `{' and `}' should
be used only to surround arguments to certain commands.  `{' and
`}' appearing anywhere else will be treated by TeX as a grouping
but treated by texinfo as themselves; this inconsistency is
undesirable, so don't let it occur.  To put special characters into
the document, put a control-q character in front; thus, type
`{' to put a `{' in the document.

It is customary in TeX to use doubled single-quote characters
to begin and end quotations.  This convention should be followed
in texinfo files.

TeX ignores the line-breaks in the input text, except for
blank lines, which separate paragraphs.  Texinfo generally
preserves the line breaks that are present in the input file.
Therefore, you break the lines in the texinfo file the way
you want them to appear in the output Info file, and let TeX
take care of itself.

This is a list of the @-commands defined in texinfo:

@@
--

@@ stands for a single @ in either printed or Info output.

@.
--

`@.' stands for a period that ends an abbreviation.  In
texinfo, it has the same effect as just `.', since you
are responsible for your own formatting in texinfo.  In a
printed manual, it generates a period that does not increase
the following interword space as periods usually do.

@:
--

`@:' is used just after a period that really does end
a sentence, if TeX will assume by its heuristics that that is not so.
This happens when there is a single-capital-letter word at
the end of a sentence: TeX thinks it is an abbreviation.
`@:' generates no output in texinfo.

@setfilename
------------

`@setfilename FILE' informs texinfo that the
Info file being produced is named FILE.  This information
is entered in every node header.  It also tells texinfo the
name for the output file.

@node
-----

`@node' defines the beginning of a new node in the Info output file
(*Note (info)top: info) It is followed by four arguments, separated
by commas, and all surrounded by square brackets.  For example,

    @node [info, tex, commands, top]

defines a node named `info', whose successor node name is `tex',
whose predecessor node name is `commands', and whose parent node name
is `top'.  What this means is that texinfo changes `@node [ARGS]'
into the special text string necessary to separate Info nodes and to
identify the node that is starting and say what its relatives are.

The successor, predecessor and parent names should be the names of
nodes defined elsewhere.  For this example, nodes named `tex',
`commands' and `top' should be defined elsewhere in the file with
other `@node' commands.  It does not matter whether they are before
or after the node that refers to them.

In TeX, `@node' is nearly ignored.  It generates no text.  Its only
function is to identify the name to use for cross-references
to the following chapter or section which makes up the body of the node.
(Cross references are made with `@note').

`@node' should always be followed by a blank line, which is then
followed by a `@chapter', `@section', `@subsection' or
`@subsubsection'.

@chapter
--------

`@chapter' identifies a chapter in the document.  It is followed by a
single argument within braces, as in

    @chapter {Texinfo Files}

In TeX, it serves to create a chapter of the document,
specifying the chapter title.

In texinfo, `@chapter' causes its argument to appear on a line by
itself, with a line of dashes inserted underneath.  Thus, in texinfo,
the above example produces the output

    Texinfo Files
    *************

@unnumbered, @appendix
----------------------

These are equivalent to `@chapter' in texinfo.
In a printed manual, they generate chapters that are numbered
differently in the table of contents.  `@unnumbered' chapters
appear without chapter numbers of any kind, and `@appendix'
chapters are given a letter instead of a number.

@section
--------

`@section' is like `@chapter' except that in TeX it makes a section
rather than a chapter.  Sections go within chapters.  In texinfo,
`@chapter' and `@section' differ only in that `@section' underlines
with `='.

@unnumberedsec, @appendixsection
--------------------------------

Use these constructs for sections within chapters made by
`@unnumbered' or `@appendix'.

@subsection
-----------

Subsections are to sections as sections are to chapters.
They are underlines with `-'.

@unnumberedsubsec, @appendixsubsec
----------------------------------

Use these constructs for subsections within sections within
chapters made by `@unnumbered' or `@appendix'.

@subsubsection
--------------

Subsubsections are to subsections as subsections are to sections.
They are underlined with periods.

@code
-----

`@code' is used to indicate text that is a literal example of input
to a program.  The text follows, enclosed in braces.  Any time you
give a sample of an expression in C, or of a command for the shell,
or any such thing, use `@code'.  In TeX, it puts the argument in bold
face.  In texinfo, it creates `...' quotation.  Example:

    To compare two files, showing text inserted or removed,
    use @code{diff}.

produces

    To compare two files, showing text inserted or removed,
    use `diff'.

@kbd
----

`@kbd' is used much like `@code'.  The difference
is that `@kbd' is for names of keys on the keyboard, or
of characters you can type.  It has the same effect as `@code'
in texinfo, but may produce a different font in a printed manual.

    To give the @code[logout] command, type the characters
    @kbd[l o g o u t Newline].

produces

    To give the `logout' command, type the characters
    `l o g o u t Newline'.

@var
----

`@var' is used to indicate metasyntactic variables.  It is much like
`@code' in use.  Its effect in texinfo is to upcase the argument; in
TeX, to italicize it.  Example:

    To delete file @var{file}, type @code{rm @var{file}}.

produces

    To delete file FILE, type `rm FILE'.

@dfn or @defn
-------------

`@dfn' is like `@code' and `@var'; but for a different purpose: it
indicates the first introductory or defining use of a technical term.
It generates italics in TeX, and double quotation marks in texinfo.
Example:

    Getting rid of a file is called @dfn{deleting} it.

    Getting rid of a file is called "deleting" it.

`@defn' and `@dfn' are synonymous.  The spelling `@defn' is being
replaced by `@dfn'.  Use the latter.

@i or @b
--------

`@i' produces italic text in a printed manual, but has
no effect on the Info file output.  `@b' does likewise,
for bold face.

@w
--

In a printed manual, `@w[TEXT]' outputs TEXT and prohibits
line breaks within TEXT.  `@w' has no effect on the Info
file output; it is the same as would result from just TEXT.

@example
--------

`@example' is used to indicate an example that is not part of the
running text.  This text is printed by TeX in a fixed width font with
no filling.  Texinfo simply indents the lines of the example by four
extra spaces.  `@example' should appear on a line by itself; this
line will disappear from the output.  Mark the end of the example
with a line containing `@end example', which will likewise disappear.
Example:

    @example
    mv foo bar
    @end example

produces

        mv foo bar

Don't use tabs in lines of an example!

@menu
-----

Info file nodes can contain "menus" which point to other nodes.  You
must type the menus in by hand, and surround them with lines
containing `@menu' and `@end menu'.  The `@menu' line changes into `*
Menu:', which indicates the beginning of a menu to the Info program.
The contents are unchanged by texinfo.  TeX throws away the entire
`@menu' construct.

    @menu
    * foo::         The node named foo tells you how to go fooing.
    * sw: switches.	Type @code[m sw] to see node @code[switches].
                    which describes the switches available here.
    @end menu

produces

    * menu:
    
    * foo::         The node named foo tells you how to go fooing.
    * sw: switches. Type `m sw' to see node `switches'
                    which describes the switches available here.

@refill
-------

If a paragraph contains sizeable @-constructs, it may look
badly filled once texinfo is through with it.

Put `@refill' at the end of the paragraph to tell texinfo to refill
the paragraph after finishing all other processing on it.  `@refill'
has no effect on TeX, which always fills everything that ought to be
filled.

@xref
-----

`@xref' generates a cross-reference.  In texinfo, it turns into
an Info "footnote" which the Info `f' command can use
to go directly to another node.  In TeX, it turns into a sentence
of the form
    See section SECTION [TOPIC], page PAGE
but does not generate a period to end it.

`@xref' must refer to an Info node created by `@node', by
the node's name.  If I were in less of a rush, I would have made a
node in this file for each texinfo command, and put in plenty of
@note's to cross-reference them together.  The big node named
`commands' would actually contain a menu naming the nodes for
individual commands.

`@xref' is followed by a pair of square brackets, containing up
to five arguments separated by commas.  Whitespace around the arguments
is ignored.  The closing square bracket must be followed by a period
or a comma, since one of those to is required to terminate an Info
footnote.  This period or comma will appear in the output, both Info
file and printed manual.

The simplest form of `@xref' takes one argument, the name of another
node in the same Info file.  Here we show the input text, followed
after a blank line by the output text for Info files and the output
text for printed manuals.

    @xref[foo], for more info.
    
    *Note foo::, for more info.
    See section NNN [foo], page PPP, for more info.

With two arguments, the second one is the used as the
name of the Info footnote, while the first argument is still
the node that the footnote points to:

    @xref[foo node, foo], for more info.
    
    *Note foo: foo node, for more info.
    See section NNN [foo node], page PPP, for more info.

A third argument replaces the node name when it actually appears
in the TeX output.  It should state the topic discussed by the
section being referenced.  Use a third argument when the node
name is unsuitable because of syntax, grammar or diction.

    @xref[foo node, foo, using foo], for more info.
    
    *Note foo: foo node, for more info.
    See section NNN [using foo], page PPP,
    for more info.

If a third argument is given and the second one is empty,
then the third argument serves both purposes:

    @xref[foo node, , using foo], for more info.
    
    *Note using foo: foo node, for more info.
    See section NNN [using foo], page PPP,
    for more info.

A fourth argument specifies the name of the Info file in which
the referenced node is located, assuming it is not the one which
the reference appears in.  `@xref' with only four arguments
is used when the reference is not within one Info file, but is
within a single printed manual--when multiple texinfo files are
incorporated into the same TeX run but make separate Info files.

    @xref[foo node, foo, using foo, myinfofile], for more info.
    
    *Note foo: (myinfofile)foo node, for more info.
    See section NNN [using foo], page PPP,
    for more info.

A fifth argument is used when referencing another Info file
which is also part of another printed manual.  It gives the
title of that manual.

    @xref[foo node, foo, using foo, myinfofile, Mymanual],
    for more info.
    
    *Note foo: (myinfofile)foo node,
    for more info.
    See section NNN [using foo], page PPP
    of Mymanual, for more info.

@infonote
---------

`@infonote' is used for cross-references to Info files for
which there are no printed manuals.  Even in a printed manual,
`@infonote' generates a reference directing the user to look
in an Info file.  The syntax is `@infonote[NODE, NAME, FILE]'.

    @infonote[foo node, fooing, FOO], to lose.
    
    *Note fooing: (FOO)foo node, to lose.
    See Info file FOO, node `foo node', to lose.

@itemize
--------

`@itemize' is used to produce sequences of indented paragraphs,
with a mark inside the left margin at the beginning of each.
The rest of the line that starts with `@itemize' should
contain the character or texinfo commands to generate such a mark.
It should ultimately result in a single character, or the indentation
will come out wrong.

The text of the indented paragraphs themselves come after the
`@itemize', up to another line that says `@end @itemize'.

Before each paragraph for which a mark in the margin is desired,
place a line that says just `@item'.

Here is an example of the use of `@itemize', followed
by the output it produces in texinfo.  Note that `@bullet'
produces a `*' in texinfo and a round dot in TeX.

    @itemize @bullet
    @item
    Some text for foo.
    @item
    Some text
    for bar.
    @end itemize

       * Some text for foo.
       * Some text
         for bar.

Texinfo indents the lines of the itemization by five additional
columns, but it does not fill them.  If `@refill' is used, the
paragraph is filled to the same width as usual.  This may be changed
some day.

@enumerate
----------

`@enumerate' is like `@itemize' except that the
marks in the left margin contain successive integers starting
with 1.  Do not put argument on the same line as `@enumerate';
none is needed.

    @enumerate
    @item
    Some text for foo.
    @item
    Some text
    for bar.
    @end enumerate

      1. Some text for foo.
      2. Some text
         for bar.

@table
------

`@table' is similar to `@itemize', but allows
you to specify a name or heading line for each item.

You must follow each use of `@item' inside of `@table'
with text to serve as the heading line for that item.

Also, `@table' itself must be followed by an argument which is either
`1', `2' or `3'.  `2' causes the `@item' strings to be treated as if
inside a `@var'.  `3' causes them to be treated as if inside a
`@code'.  `1' says that the `@item' strings should be used as given.

    @table 3
    @item foo
    This is the text for
    @code[foo].
    @item bar
    Text for @code[bar].
    @end table

produces

    `foo'
         This is the text for
         `foo'.
    `bar'
         Text for `bar'.

conditionals
------------

You may not be able to use the same text for TeX and texinfo.
Use the conditional commands to specify which text is for TeX
and which is for texinfo.

`@ifinfo' begins text that should be ignored by TeX.  It should
appear on a line by itself.  End the texinfo-only text with a line
containing `@end ifinfo'.

Likewise, `@iftex' and `@end iftex' lines delimit code that should be
ignored by texinfo.


File: texinfo  Node: info, Prev: commands, Up: top

Converting Texinfo Files into Info Files
========================================

Just visit a texinfo file and invoke

    `Meta-x texinfo-format-buffer'

to convert it to an Info file.  A new buffer is created
and the Info file text is generated there.  `C-x C-s'
will save it under the name specified in the `@setfilename'
command.
